<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>

<head>
  <title>KABC Client - Examples</title>
  <meta name="GENERATOR" content="Quanta Plus">
</head>
<body>
  <h1>KABC Client - Usage examples</h1>
  <ul>
    <li><a href="#list">List</a></li>
    <li><a href="#search">Search</a></li>
    <li><a href="#add">Add</a></li>
    <li><a href="#remove">Remove</a></li>
    <li><a href="#merge">Merge</a></li>
  </ul>
  <p>
      If you have interesting use cases or scripts using kabcclient, 
      <a href="mailto:kevin.krammer@gmx.at">let me know</a> about it!<br>
  </p>
  <h2><a name="list">Examples for list</a></h2>
  <p>
    Export all contacts to a vcard file
    <pre>
    kabcclient --list -of vcard -oc UTF8 > exported-contacts.vcf
    </pre>
    This can be written even shorter because of the defaults for output format
    and output codec and the shorter form of the --list command
    <pre>
    kabcclient -L > exported-contacts.vcf
    </pre>
    <b>vcard</b> is the default output format as it can contain all data for a
    addressbook entry. <b>UTF8</b> is the default encoding for <b>vcard</b> because
    the VCard specification requests that.<br>
    However, if you need a different encoding, for example because another program
    doesn't understand UTF-8, you can always override the default choice.<br>
    Same example but encode output in the local encoding:
    <pre>
    kabcclient --list -oc LOCAL > exported-contacts.vcf
    </pre>
  </p>
  
  <h2><a name="search">Examples for search</a></h2>
  <h3>Simple searches</h3>
  <p>
    Search for contacts contacts that have "john" in either name or email addresses:
    <pre>
    kabcclient -S john
    </pre>
    Doing the same but read from stdin:
    <pre>
    echo "john" | kabcclient -S
    </pre>
    Both variants use a couple of option defaults. The full commandline, but still using
    <b>-S</b> instead of search's long form <b>--search</b>, would look like this
    <pre>
    kabcclient -if search -ic LOCAL -of vcard -oc UTF8 -S john
    </pre>
    <b>search</b> is a special input format parser, which will apply the input text to
    both name and email fields so either can match contacts in the addressbook.<br>
    As discussed under <a href="#list">examples for list</a> default for output is
    <b>vcard</b> in combination with <b>UTF8</b>
  </p>
  <h3>Matching options</h3>
  <p>
    Matching is <u>case insensitive</u> by default, i.e. the input "john" and the input "John"
    will result in the same output.<br>
    In case you want to switch text matching to <u>case sensitive</u>, add the commandline
    switch <b>--match-case</b>:
    <pre>
    kabcclient --match-case -S John
    </pre>
  </p>
  <h3>Advanced searches</h3>
  <p>
    Searching for more than one name is as simple as adding them to the commandline:
    <pre>
    kabcclient -S John Jane Bob
    </pre>
    This start a search for "John", then search for "Jane" and finally search for "Bob".<br>
    When reading from stdin the <b>search</b> input format parser, like most other input
    format parsers as well, assumes that each line is a separate search, or in other words
    that one line is one lookup string:
    <pre>
    echo "John Bob" | kabcclient -S
    </pre>
    Will look for someone called "John Bob", while
    <pre>
    ( echo "John" ; echo "Bob" ) | kabcclient -S
    </pre>
    will first look for all "Johns" and the for all "Bobs"
  </p>
  <p>
    A more realistic input situation would be this
    <pre>
    kabcclient -S
    </pre>
    Called like this, or even without the -S as search is the default operation, will let
    <b>kabcclient</b> wait for input directly from the terminal it runs on, i.e.
    each line you type will trigger a search for it.
  </p>
  <h3>Output customization</h3>
  <p>
    The full VCard data of a contact might be too much, for example we could be only
    interested in poeple's emails:
    <pre>
    kabcclient -of email -S John
    </pre>
    This will list the primary email address of all "Johns" in the addressbook.<br>
    To get not just the primary email address per contact but all available addresses,
    the additional output format options can be put to use:
    <pre>
    kabcclient -of email -of-opts allemails -S John
    </pre>
    In cases where more than one "John" is in the addressbook, this can easily make it
    impossible to know which email address belongs to which "John".<br>
    But fortunately the <b>email</b> output knows a second option:
    <pre>
    kabcclient -of email -of-opts allemails,withname -S John
    </pre>
    Multiple options are separated by commas. To get a list and description of the
    available format options, just use <b>help</b> as the parameter instead:
    <pre>
    kabcclient -of email -of-opts help
    </pre>
  </p>
  <h2><a name="add">Examples for add</a></h2>
  <h3>Operation basics</h3>  
  <p>
    The add operation really <u>adds</u> entries to the addressbook, i.e. if the input is
    one of the entries which are already in the addressbook, you will have a duplicate.<br>
    The advantage is that is will not overwrite any data currently in the addressbook.<br>
    Add requires a input format to be specified because the default input format <b>search</b>
    isn't a good choice for this kind of operation.
  </p>
  <p>
    Adding a new contact based on the name and email address as commonly formatted by
    email programs:
    <pre>
    kabcclient -if email --add "Marilyn Monroe &lt;mmonroe@moviestars.com>"
    </pre>
    Of course the possibilty to read from stdin still applies:
    <pre>
    echo "Marilyn Monroe &lt;mmonroe@moviestars.com>" | kabcclient -if email --add
    </pre>
    Output of both commands will be the VCard representation of the contact data
    (default output format being <b>vcard</b> as discussed in
    <a href="#list">examples for list</a>)
  </p>
  <h3>Using the add operation as an format converter</h3>
  <p>
    A variant of the above exmple is to use <b>kabcclient</b> as a VCard converter:
    <pre>
    echo "Marilyn Monroe &lt;mmonroe@moviestars.com>" | kabcclient -if email --nosave --add
    </pre>
    The <b>--nosave</b> option keeps the new contact entry from actually being written to
    the addressbook's permanent location, e.g. the standard addressbook file, so the only
    affect the command has is to read the provided name and email combination and write the
    resulting contact to stdout, which, as shown above, is formatted by the <b>vcard</b>
    output format
  </p>
  <h3>Importing previously exported contacts</h3>
  <p>
    Consider you have exported all your contacts to a VCard file on one machine:
    <pre>
    kabcclient --list > contacts.vcf
    </pre>
    and you want to import them on a different machine or on a different user account:
    <pre>
    cat contacts.vcf | kabcclient -if vcard -A
    </pre>
    Remember that this will not overwrite any data of the target addressbook but
    might lead to duplicate entries.
  </p>
  
  <h2><a name="remove">Examples for remove</a></h2>
  <h3>Operation basics</h3>  
  <p>
    The remove operation <u>deletes</u> contacts from the addressbook, unless the
    <b>--nosave</b> option keeps it from actually writing the changes to the permanent
    addresbook location.<br>
    As an additional safety measure, remove will only delete contacts that match
    <u>unambiguoulsy</u>, i.e. if more than one contact matches none of them is
    deleted.<br>
    Any deleted contact is written to stdout
  </p>
  <p>
    Trying to remove contact data for "John" from the addressbook:
    <pre>
    kabcclient -R John
    </pre>
    As explained in the <a href="#search">examples for search</a> the input "John"
    will be used by the default input format parser <b>search</b> for matching
    against name and email addresses of contacts in the addressbook and matches
    will be case insensitive.<br>
    Depending on the number of "John" occurences in the addressbook, this might
    not yield an unambiguous match, thus resulting in no contact being deleted.
  </p>
  <h3>Better input for more exact matching</h3>
  <p>
    By providing more information about the contact to remove, the chance of getting
    a clear single match increases:
    <pre>
    kabcclient -if email -R "John Meyer &lt;jmeyer@somecompany.com>"
    </pre>
    Using the <b>email</b> input format parser provides name and email to match
    against possible candiates from the addressbook.
  </p>
  <p>
    The best possible matching criteria is provided by the <b>uid</b> input format parser.<br>
    An UID is a unique identifier created by the addressbook itself, thus matching exactly just
    one contact entry.<br>
    UIDs can be retrieved by using other operations, e.g. --list and --search, using the
    <b>uid</b> output format:
    <pre>
    kabcclient -of uid -L > all-uids.txt
    
    cat one-uid.txt | kabcclient -if uid -R
    </pre>
    As a consequence the following command sequence would empty the whole addressbook
    if the <b>--nosave</b> option would not be present:
    <pre>
    kabcclient -of uid -L | kabcclient -if uid --nosave -R
    </pre>
  </p>
  <h2><a name="merge">Examples for merge</a></h2>
  <h3>Operation basics</h3>  
  <p>
    The <b>merge</b> operation is quite similar to the <b>add</b> operation, but instead
    of adding new contact entries to the addressbook, it tries to add the new data
    to already existing contacts.<br>
    As a result it requires <u>unambiguous</u> matches like the <b>remove</b> operation.
  </p>
  <p>
    As merging information results in changes to the addressbook, the <b>--nosave</b>
    switch can be used to just test the results some input data would have on the
    addressbook contacts.<br>
    For each successull match <b>kabcclient</b> will write the merged contact data to
    stdout, just like it would for new entries when using <b>add</b>.<br>
    As the program needs both something to match and some data to add, simple input
    formats like <b>name</b> won't be very effective.<br>
  </p>
  <h3>Adding additional e-mail addresses</h3>
  <p>
    Assuming that a person's name is enought information to find a single matching
    contact in the addressbook, the following example will add the given e-mail
    address unless it is already part of the contacts data:<br>
    <pre>
    kabcclient -if email -M "John Meyer &lt;jmeyer@somecompany.com>"
    </pre>
    More effective merge operations can be conducted by using the <b>vcard</b> or
    <b>csv</b> input formats.
  </p>
  <h3>Merging backups into current addressbook</h3>
  <p>
    As discussed in the <a href="#remove">examples for remove</a> the best matching
    is provided by the UIDs the addressbook generates to uniquely identify contacts.<br>
    Assume that a backup of the contacts has been creates using the <b>list</b> operation
    and other kinds of access have corrupted parts of the contacts in the addressbook.<br>
    <pre>
    cat exported-contacts.vcf | kabcclient -if vcard -M
    </pre>
    Data that is present for contacts in the input file but not present for the
    respective contact in the addressbook will be added to the one in the addressbook.
  </p>
  <hr>
  <p>
    Author: Kevin Krammer, 8010 Graz, Austria
  </p>
</body>
</html>
